Internet Info 1994 March

home *** CD-ROM | disk | FTP | other *** search

/ Internet Info 1994 March / Internet Info CD-ROM (Walnut Creek) (March 1994).iso / networking / terms / kermit / c / qlker.doc < prev next >

Wrap

Text File | 1988-08-16 | 34.2 KB | 1,152 lines

QL-KERMIT Edition DRAFT, 4-May-87 QL-KERMIT - Documentation ========================= 1. Introduction ---------------- This documentation briefly describes my (with acknowlegements to others - see the comments at the front of the main program) implementation of Kermit on the Sinclair QL. It is assumed that the reader is reasonably familiar with Kermit and how to use a "standard" Kermit program. The first release version of QL-Kermit (referred to from here on as 'QLK') comprises about 120K bytes of C source, compiling to about 55K bytes of object code. Although the object will run on a standard unexpanded QL, a memory expansion (preferably to the maximum 640K) and at least one disc drive is an essential configuration for compilation or development work. The Metacomco C Development Kit is also required. Refer to the Building QL-Kermit section for information on building QLK from source. Page 1 QL-KERMIT Edition DRAFT, 4-May-87 2. Capabilities at a Glance ---------------------------- Local operation Yes Remote operation No Transfer text files Yes Transfer binary files Yes Wildcard send No ^X/^Z interruption Yes Filename collision avoidance No Can time out Yes 8th-bit prefixing Yes Repeat count prefixing No Alternate block checks No Terminal emulation Yes Communications settings Yes Transmit BREAK No IBM mainframe communication No Transaction logging No Session logging No Raw transmit No Act as server No Talk to server Yes Advanced server functions No Advanced commands for servers Limited Local file management Unnecessary Handle file attributes No Command files Yes Command macros No XON/XOFF flow control No Split baud rates No I have not implemented some of these features for various reasons: (a) they are not relevant to my intended use of QLK; (b) they would be impossible to implement on the QL hardware (e.g. transmit BREAK); (c) they may be implemented at a later date. Note: At present I have only tested QLK transferring files to and from a BBC running Lancs-Kermit (version 1.45). Therefore I have only extensively tested features which are used by this configuration. I cannot guarantee that other facilities work well enough, if at all. Page 2 QL-KERMIT Edition DRAFT, 4-May-87 3. Using the program --------------------- Assuming that the binary version of QLK has been obtained or built, it can be run by using the EXEC command (or, if you have Toolkit or Super Toolkit fitted, EX). The console window will clear, and the version string will be displayed. At this point it will look for a startup file which will typically contain a series of Kermit commands to configure QLK for the intended application. As supplied the file searched for is "flp1_qlk_take"; it can be altered to look for a different file or on a different device by changing the symbol DFTAKE in the header file ker_h. When this startup file has ended, or if none is found, the prompt "QLK>" will be displayed. (Fairly) standard Kermit commands can now be entered; these are listed in the next section. The following control keys can be used to control and edit command lines: F1 (HELP) When pressed at the beginning of a field, indicate what this field needs to be completed with, or display a list of options. F3 (DELETE LINE) Abandon the current command entirely. ^U can also be used. F4 (COMPLETE/DEFAULT) If pressed at the beginning of a field, supply and display the default value for that field (if any). If pressed in the middle of a 'keyword' field, complete the field if what has been typed already is valid and unambiguous. If these do not apply, the key is ignored. ESC can also be used. F5 (DELETE CHARACTER) Delete the character to the left of the cursor. The standard QL CTRL-LEFT, or ^H, can also be used. ^R (REDISPLAY) Replay the current command line (e.g. if the screen has been corrupted by another job's output). Commands may be entered in either upper or lower case (or indeed any mixture of the two). Note that CTRL-C can be used to switch the keyboard input to another job (assuming that QLK has been started by EXEC or EX); this makes it unnecessary to include commands in QLK for local file management. During file transfer, the following control keys are recognised: ^X (INTERRUPT FILE) If sending, end transmission of the current file and send an EOF packet with a Discard request. Note that since the current version of QLK does not support the sending of multiple files, this key has an identical action to ^Z. If receiving, request the remote system to abort the transmission of the current file and continue with the next one (if it is Page 3 QL-KERMIT Edition DRAFT, 4-May-87 sending multiple files). ^Z (INTERRUPT BATCH) If sending, end transmission of the current file and send an EOF packet with a Discard request, followed by an EOT packet to end the batch. If receiving, request the remote system to abort the transmission of the current file and not send any more (if it is sending multiple files). ^T (FORCE TIMEOUT) If pressed while QLK is waiting for a packet to be received, the wait will be abandoned and a timeout simulated, thus forcing QLK to resend the previous packet or acknowledgment. This is useful for manually unjamming the deadlock caused by a lost packet, if for some reason the timeout facility is not being used. ^E (FATAL ERROR) If for some reason the remote system does not support ^X/^Z interruption, these control keys will have no effect in stopping the transfer. In this case pressing ^E will cause an Error packet to be sent with an appropriate message - this should cause any remote system to stop. Page 4 QL-KERMIT Edition DRAFT, 4-May-87 4. Commands ------------ The commands available in QLK are listed here, with the syntax and a description for each. Note that a command or required keyword need not be typed in full - only enough characters need be typed to make what is meant unambiguous. UPPERCASE is to be typed literally; lowercase indicates variable parameters; [brackets] indicate optional parameters. Possible options are seperated by ','s. CONNECT This enters terminal emulation on the currently selected serial line. The screen will clear and the cursor reappears in the top left corner. Terminal emulation is extremely dumb, with no support for any special features of the QL screen or any standard video terminal. The special keys recognised are: F2 (EXIT) This returns to Kermit command mode. F3 (NULL) This sends the ASCII code 0. F4 (^C) This sends the ASCII code 3. F5 (DEL) This sends the ASCII code 127. ENTER (EOL) Sends the currently defined end of line sequence, as set by SET ENTER. All other keys are sent to the serial line. If the LOCAL-ECHO option has been set to ON, the key press is also echoed to the screen. ENTER is always echoed as a newline regardless of the setting of the end of line sequence. DO command-line This is equivalent to REMOTE HOST in most other versions of Kermit. It sends the specified 'command-line' to be executed by the remote server, and displays the results on the QL screen. EXIT Exits the Kermit program. Page 5 QL-KERMIT Edition DRAFT, 4-May-87 FINISH Sends a command to a remote server requesting it to exit server operation, and return to Kermit command mode. GET remote [local] Asks the remote server to send a file. 'remote' is the file to be sent, in the filename syntax appropriate to the remote system. 'local' is the QL filename to store it under; if omitted, the name that the remote sends in the File-Header packet will be translated to a suitable QL filename. If 'local' is not given, or if it is given but it includes no QL device prefix, the file will be stored on the current DESTINATION device. Note that if the server sends multiple files as a result of including wildcards in 'remote', then 'local' must not be given, otherwise the QL will overwrite the just-received file each time a new one is started. However, QLK does not check this, and it may even be useful in some applications (e.g. to see the files on the screen, give "scr_" as the local name). HELP Displays a summary of the control keys available in command, transfer and terminal modes. QUIT Equivalent to EXIT. RECEIVE [local] Waits for a file to be sent from a remote non-server. 'local' is the filename that it will be stored under; if omitted, the name that the remote sends in the File-Header packet will be used (as for GET). The remarks under GET regarding multiple files also apply here. SEND local [remote] Sends a file to a remote, whether a server or not. 'local' is the QL file to be sent. 'remote', if given, is the name that will be sent in the File-Header packet; if omitted, the local name will be used. If 'local' has no QL device prefix, the current SOURCE device will be used. Page 6 QL-KERMIT Edition DRAFT, 4-May-87 SET parameter option SET sub-section parameter option Controls various options of the Kermit program. See the next section. SHOW [what] Displays the current Kermit settings and parameters. 'what' indicates what is to be shown, it may be: ALL Everything except VERSION COMMUNICATION Settings relating to the serial ports and terminal emulation DEVICES Current default devices (see SET DEVICE) FILE Settings relating to file transfer PREFIX The current quote characters SYSTEM Settings which don't fit in anywhere else TRANSFER Protocol parameters, timeouts, etc. VERSION The current QLK version If 'what' is omitted, ALL is assumed. TAKE filename Read and execute Kermit commands from a file. No file suffix is enforced, but the suggested one is "_take". If the filename given has no QL device prefix, then the current TAKE device will be used. If the TAKE-ECHO option is set to ON, command lines read from a TAKE file will be listed on the screen prior to them being executed. They will be preceded by "TAKE-n>", where n is the TAKE file nesting level, to distinguish them from commands typed at the keyboard. The TAKE command can be used within a TAKE file, thus allowing them to be nested to a maximum of 10 levels. However, if an invalid command is read, or if an error occurs during a file transfer, the entire stack of TAKE files will be abandoned if the TAKE-ABORT option is set to ON. (This does not include a transfer interruption initiated by ^X or ^Z; however it does include a fatal error initiated by ^E). This can be disabled by setting the TAKE-ABORT option to OFF. Page 7 QL-KERMIT Edition DRAFT, 4-May-87 5. The SET command ------------------- The options that can be controlled by the SET command are given below. Note that SEND, RECEIVE, FILE and DEVICE are logically sub-sections, although they are described here as if they were seperate options. BAUD speed Set the baud rate for the currently set serial line. The valid rates are those listed in the QL manual. The setting on entry is for the current speed to be retained (as set by the SuperBasic BAUD command). CONTROL-QUOTE char Sets the character that QLK will prefix control characters in packets that it sends with, and indicate to the remote system that it will do so. This is normally '#', but can be changed for special applications. Note that QLK, when receiving packets, always uses the quote character the remote has asked it to. DEBUGGING OFF,ON,FULL Sets the debugging level. OFF is the initial setting, no information is displayed. ON causes messages regarding file manipulation and packet read failures to be displayed. FULL in addition displays information regarding the switcher state, and the contents of all incoming and outgoing packets. DELAY time Sets the wait, in seconds, between the SEND command being accepted and the file transfer starting. If connected to another microcomputer Kermit, this gives time for the RECEIVE command to be typed on the other system. The initial setting is 5 seconds. While QLK is waiting ("Pausing" displayed) the wait can be interrupted by pressing any key; the transfer will start immediately. DEVICE DESTINATION device Sets the default destination device for file transfers. If the opening of the file for the GET or RECEIVE commands fails due to a "Not found" error, Page 8 QL-KERMIT Edition DRAFT, 4-May-87 this string will be prepended to the file name and another attempt made. No checks are made on the validity of this device, and the trailing underscore must be included. Note that if the first attempt at opening the file fails for some reason other than "Not found" (e.g. "In use") the addition of the device prefix will not be done and an error message will be issued immediately. The initial setting is "flp2_". DEVICE SOURCE device Sets the default source device for file transfers. If the local file given in the SEND command is not found, this device will be prepended to the name given and another attempt made to find it. The remarks applying to DESTINATION regarding other errors also apply here. The initial setting is "flp2_". DEVICE TAKE-FILE device Sets the default source device for command files read by the TAKE command. The initial setting is "flp1_". EIGHT-BIT-QUOTE char Sets the character that QLK will use for 8th-bit quoting, if it is necessary and the remote system agrees to use the same character. This is normally '&', but can be changed for special applications. ENTER CR,LF,CRLF,LFCR Sets the character(s) that will be transmitted in terminal emulation mode when the ENTER key is pressed. CR is Carriage Return (ASCII 13); LF is Line Feed (ASCII 10). If it is set to CRLF or LFCR then two characters will be transmitted in succession. The initial setting is CR. FILE INCOMPLETE DELETE,KEEP Controls what happens to a partially received file if a transfer is abandoned (by a ^X or ^Z interrupt) or fails (due to an error or a ^E interrupt). If set to DELETE, the file is deleted; if set to KEEP, the partial file is retained. The initial setting is DELETE. Page 9 QL-KERMIT Edition DRAFT, 4-May-87 FILE NAME NORMAL,UNTRANSLATED Controls whether file names sent or received in File-Header packets are translated to or from a standard QL format before use. If set to UNTRANSLATED, when sending the name sent will be identical to the name the QL file was opened with (not necessarily that given on the command line); for receive, the name contained in the packet will be used for the QL file (but the DESTINATION device will still be prepended if necessary). If set to NORMAL, the QL filename will be translated to or from the "standard" Kermit format (as described in the Protocol Manual). The conversions applied for sending are: (a) The QL device prefix is stripped off (b) Lowercase letters are converted to uppercase (c) The last '_', if any, is changed to a '.'. The conversions applied on receiving are: (a) Uppercase letters are converted to lowercase (b) Any '.'s are converted to '_'s. Note that, if a remote name is given in the SEND command, this will be sent verbatim in the packet, even if NORMAL mode is set. Similarly, if a local name is given for GET or RECEIVE, this will not be translated (apart from the possible addition of the DESTINATION device). The initial mode is NORMAL. FILE SUFFIX [string] Sets a possible suffix string which is added to files sent by QLK, to identify their source when they are stored on a remote filestore. If a 'string' is given, this (preceded by a '_') will be appended to outgoing filenames before undergoing translation. This suffix will not be added if a remote name is given explicitly, or if UNTRANSLATED mode is set. If 'string' is not given, no suffix will be added. Initially, no suffix is set. An example may be in order here to clarify the interaction between send translation and suffix addition. If the SOURCE device is set to "flp2_" and the SUFFIX to "ql", then the command: SEND main_c will search first for "main_c" (and not find it) and then find "flp2_main_c" (assuming that it exists on that device). Firstly, the suffix will be added to that name, giving "flp2_main_c_ql", then this will be translated to the Kermit format - making the name sent in the File-Header packet "MAIN_C.QL". Page 10 QL-KERMIT Edition DRAFT, 4-May-87 If no file suffix is set, the name "flp2_main_c" will be translated to Kermit format, thus sending "MAIN.C". If UNTRANSLATED mode had been set, then the name sent in the packet would be "flp2_main_c". FILE TYPE ASCII,BINARY Controls whether end-of-line translation is applied to file data sent or received during a transfer. If set to BINARY, no translation is done; this allows object files, etc. to be sent and received exactly as they appear in the filestore. If set to ASCII, end-of-line translation is done as follows: For sending, a QL end of line (LF, ASCII 10) is sent in the packet as the prefix sequence "#M#J", assuming that the control-quote in use is '#'. A carriage return (ASCII 13) encountered in the file will be sent as "#M". For receiving, "#M" is ignored and "#J" is written to the file as LF. This has the effect (assuming that the option is set correctly at both ends of the link) of allowing a printable text file on the sending system to become a printable text file on the receiving system, regardless of what means the other system uses to represent end of line. Note that the ASCII/BINARY setting has no bearing on whether the 8th-bit of a byte is sent, with quoting or otherwise. It affects end of line translation only. The initial setting is ASCII. LINE [1,2] Sets the serial port to be used for data transfer. '1' selects ser1, '2' selects ser2. If '1' or '2' is not given, the old line is freed (thus allowing another job to use that serial port) but no new line is opened. Initially, no line is set. LOCAL-ECHO OFF,ON Controls whether keys pressed in terminal mode are echoed to the screen by the QL, or by the remote computer. Note that if it is set to ON, the ENTER key is always echoed as a newline regardless of the setting of the ENTER action. The initial setting is OFF. PADDING [amount [character]] Controls whether padding is inserted after a transmitted packet, to allow Page 11 QL-KERMIT Edition DRAFT, 4-May-87 for communication line delays or remote system requirements. 'amount' is the number of pad characters that are to be transmitted; the default is 0 (no padding). 'character' is the character to be used (in decimal); the default is NUL (ASCII 0). If 'amount' and 'character' are omitted, no padding will be done. Note that the amount of padding and the character used are subject to negotiation in the Send-Init packet exchange. The algorithms used are explained later. PARITY NONE,ODD,EVEN,MARK,SPACE Selects the parity setting that will be used by the QL for transmission, and checked on reception. The initial setting is NONE. The parity setting interacts with whether 8th-bit quoting will be specified or requested in the Send-Init packet exchange. See the notes later regarding this exchange. RECEIVE END-OF-LINE code Specifies the end-of-line character that QLK will request the remote system to terminate a packet with. This is specified in decimal; the initial setting is Carriage Return (ASCII 13). Note that QLK does not require any end of packet marker, so this option is redundant. It also appears pointless to allow this character to be specified in the Send-Init exchange, since if a different terminator to the default was required the Send-Init packet or its acknowledgement could not be received! RECEIVE MARKER code Specifies, in decimal, the character that QLK will look for to indicate the start of an incoming packet. The initial setting is SOH (ASCII 1). RECEIVE PACKET-LENGTH length Specifies the maximum packet length that QLK will request the remote system to send. The initial setting is the maximum of 94. A sensible minimum is about 30, but this is not enforced by QLK. RECEIVE TIMEOUT time Specifies the time, in seconds, that QLK will wait for an incoming packet (if the timer is enabled). The initial setting is 20. The timeout used is subject to Send-Init negotiation. Page 12 QL-KERMIT Edition DRAFT, 4-May-87 RETRIES number Sets the number of times that QLK will retransmit a packet when the expected reply is not received succesfully. This includes packet read timeouts (if the timer is enabled), timeouts forced by ^T, packets received with a bad checksum or unexpected reception of a previously received packet. If this limit is exceeded, the transaction will be aborted. Note that the retry limit applies to the reception of one particular packet, and not the total number of retries in a transaction. The initial setting is 5. SEND END-OF-LINE code Specifies the end-of-line character that QLK will terminate a packet with. This is specified in decimal; the initial setting is Carriage Return (ASCII 13). The remarks under the corresponding RECEIVE option regarding the specification of this parameter in the Send-Init exchange also apply here. SEND MARKER code Specifies, in decimal, the character that QLK will transmit to indicate the start of a packet. The initial setting is SOH (ASCII 1). SEND PACKET-LENGTH length Specifies the maximum packet length that QLK will send to the remote system. The initial setting is the maximum of 94. A sensible minimum is about 30, but this is not enforced by QLK. This length is subject to Send-Init negotiation. SEND TIMEOUT time Specifies the time, in seconds, that QLK will ask the remote system to wait for an incoming packet, if it has a timeout facility. The initial setting is 20. TAKE-ABORT OFF,ON Controls whether TAKE files are abandoned when a command or transfer error occurs. If it is set to ON, the entire stack of TAKE files (i.e. the one containing the command causing the error, as well as any that called it) is abandoned and control returns to the keyboard prompt. If set to OFF, Page 13 QL-KERMIT Edition DRAFT, 4-May-87 the error is ignored and execution continues with the next command in the TAKE file. See the description of the TAKE command for more information. The initial setting is ON. TAKE-ECHO OFF,ON Controls whether command lines read from a TAKE file are echoed on the screen before execution. If set to ON, they are listed with a "prompt" identifying their source and the current level of TAKE file nesting. See the TAKE command for more information. The initial setting is ON. TIMER OFF,ON Controls whether QLK will time out if a packet being waited for is not received within the specified or negotiated time. If set to OFF, QLK will never time out and will wait indefinitely if a packet does not arrive (execpt that a timeout can be simulated with ^T). If set to ON, timeout processing will be performed normally. The initial setting is ON. Page 14 QL-KERMIT Edition DRAFT, 4-May-87 6. Notes on Send-Init parameter negotiation -------------------------------------------- Certain parameters relating to the file transfer that is just about to start are negotiated between the two sides in the Send-Init packet exchange. The algorithms QLK uses to derive the parameters eventually used in the file transfer are described here. Note that "send" and "receive" here refer to packets and not necessarily file data. Also observe that some Kermit implementations may well ignore the parameters requested in the exchange, and either impose their own defaults or some compromise (as QLK does in some cases). (a) Packet length QLK asks the remote system to send it packets no longer than the RECEIVE PACKET-LENGTH setting, but will not fail if for some reason this request is ignored. Initially the packet length that it sends is that specified by SEND PACKET-LENGTH; however if the remote system requests it to send a shorter packet, QLK will do that. The eventual length used is the minimum of the QLK setting and the remote request. (b) Timeout QLK requests the remote system to time out (if it is capable of doing so) after the SEND TIMEOUT interval. The initial timeout QLK uses is that set by RECEIVE TIMEOUT; if the remote system specifies that QLK should use a longer interval, it will do so. The eventual receive timeout used is the maximum of the QLK setting and the remote request. (c) Padding amount QLK does not require padding on receive, and always specifies that no padding should be sent to it. Initially the amount of padding sent, and the character used, are those set by PADDING; after the exchange, if a greater number of padding characters are requested by the remote, that number will be used. The padding character sent is always that specified in the packet. (d) End of line QLK sends the first packets with the terminator defined by SEND END-OF-LINE, and then uses that requested by the remote, if given. QLK does not require a terminator on incoming packets, but requests that set by RECEIVE END-OF-LINE for completeness. Page 15 QL-KERMIT Edition DRAFT, 4-May-87 (e) Control quote The quote characters are not used until he Send-Init exchange is over, therefore no initial setting is relevant. QLK will inform the remote system that it will send data using the character set by CONTROL-QUOTE; for receiving data it will use the quote character the remote specifies. (f) 8th-bit quote The current parity setting interacts with 8th-bit quote negotiation as follows: If the parity setting is NONE, QLK need not do 8th-bit quoting, but will do so if the remote requires it. In this case, the quote character used is that specified by the remote, if it requires 8th-bit prefixing to be done. If the remote need not do 8th-bit quoting either, then it will not be done. The character specified by EIGHT-BIT-QUOTE is irrelevant in this case. If the parity setting is one which permits only 7-bit transmission, QLK will specify that it needs to do 8th-bit prefixing. The quote character used will depend on which side initiates the exchange: If QLK sends the Send-Init packet, it will request that 8th-bit quoting is to be done using the character currently set. If the remote replies that it will use the same character, or it will optionally do so, that character will be used for the transaction. In the case where QLK reads the Send-Init packet and acknowledges with its own parameters, if the remote has specified optional quoting then QLK will indicate that it must use the set character. If the remote specifies a quote character, thus indicating that it must prefix, then QLK will use the character specified too. (g) Other parameters QLK supports only checksum type 1, and assumes that the remote will agree. Repeat count prefixing is not supported; nor are any exotic features such as file attributes, sliding windows or long packets. Note that, if any parameters are not specified by the remote system (i.e. if it sends a short parameter packet), QLK will continue to use the initial settings as they were at the start of the transaction. Page 16 QL-KERMIT Edition DRAFT, 4-May-87 7. Building QL-Kermit from source ---------------------------------- To build QLK from source requires a little more than the standard QL configuration. The Metacomco C Development Kit is essential, and at least one disc drive. Expansion memory, if available, would greatly speed up compilation; the maximum of 640K is preferred. The source files required are: main_c Main program and global data cmd_c Command processor fns_c Protocol support routines swit_c Protocol state switcher us1_c User commands us2_c The SET command term_c Terminal emulation sbr_c General subroutines ker_h General definitions cmd_h Command processor definitions usr_h User command and option definitions kermit_link Linker control file Also required, as supplied with the C Development Kit, are stdio_h, ctype_h, qdos_h and fcntl_h. The device names in the #include statements and linker control file have been set assuming that a full configuration of 640K of memory and 2 discs is available and that the source and object files will be stored on a RAMdisc, which must be of at least 450 sectors. The final executable file is best written to disc, since if the RAMdisc is made big enough to hold this as well the C compiler will be a very tight fit in the remaining memory. The system include files are assumed to be on flp1_. For other configurations, the files will have to be edited to reflect the disposition of source and system files. Whatever the configuration, when all the source files have been compiled they can be linked with the Linker command line: -with DEV1_kermit -nolist -prog DEV2_kermit_exec where DEV1 is the device that kermit_link resides on, and DEV2 is the device that the executable file is to be written to. Note that the Linker control file may also have to be edited to reflect the device that the object files are held on. After this has been done, Kermit can be run using EXEC (or EXEC_W). Page 17 QL-KERMIT Edition DRAFT, 4-May-87 8. Acknowledgments ------------------- Thanks are due to: Robert Coughlan, lately of Liverpool University, for writing the original version of QL-Kermit and making it available via Lancaster. The Lancaster Kermit Distribution Service, and especially Alan Phillips whose excellent implementation of BBC-Kermit inspired me to provide it with something to talk to. David Gordon; for programming help, QL advice and the loan of a machine and supporting bits. The writers of the original C-Kermit, from which many of the algorithms used in QLK are taken; also the original developers of the Kermit protocol. Sir Clive Sinclair; for taking a great CPU, building a set of totally inadequate hardware around it and making the result available very cheaply.